<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "https://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<meta http-equiv="X-UA-Compatible" content="IE=9"/>
<meta name="generator" content="Doxygen 1.8.15"/>
<meta name="viewport" content="width=device-width, initial-scale=1"/>
<title>CryptoAuthLib: CryptoAuthLib - Microchip CryptoAuthentication Library</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="jquery.js"></script>
<script type="text/javascript" src="dynsections.js"></script>
<link href="navtree.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="resize.js"></script>
<script type="text/javascript" src="navtreedata.js"></script>
<script type="text/javascript" src="navtree.js"></script>
<script type="text/javascript">
/* @license magnet:?xt=urn:btih:cf05388f2679ee054f2beb29a391d25f4e673ac3&amp;dn=gpl-2.0.txt GPL-v2 */
  $(document).ready(initResizable);
/* @license-end */</script>
<link href="search/search.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="search/searchdata.js"></script>
<script type="text/javascript" src="search/search.js"></script>
<link href="doxygen.css" rel="stylesheet" type="text/css" />
</head>
<body>
<div id="top"><!-- do not remove this div, it is closed by doxygen! -->
<div id="titlearea">
<table cellspacing="0" cellpadding="0">
 <tbody>
 <tr style="height: 56px;">
  <td id="projectalign" style="padding-left: 0.5em;">
   <div id="projectname">CryptoAuthLib
   </div>
   <div id="projectbrief">Microchip CryptoAuthentication Library</div>
  </td>
 </tr>
 </tbody>
</table>
</div>
<!-- end header part -->
<!-- Generated by Doxygen 1.8.15 -->
<script type="text/javascript">
/* @license magnet:?xt=urn:btih:cf05388f2679ee054f2beb29a391d25f4e673ac3&amp;dn=gpl-2.0.txt GPL-v2 */
var searchBox = new SearchBox("searchBox", "search",false,'Search');
/* @license-end */
</script>
<script type="text/javascript" src="menudata.js"></script>
<script type="text/javascript" src="menu.js"></script>
<script type="text/javascript">
/* @license magnet:?xt=urn:btih:cf05388f2679ee054f2beb29a391d25f4e673ac3&amp;dn=gpl-2.0.txt GPL-v2 */
$(function() {
  initMenu('',true,false,'search.php','Search');
  $(document).ready(function() { init_search(); });
});
/* @license-end */</script>
<div id="main-nav"></div>
</div><!-- top -->
<div id="side-nav" class="ui-resizable side-nav-resizable">
  <div id="nav-tree">
    <div id="nav-tree-contents">
      <div id="nav-sync" class="sync"></div>
    </div>
  </div>
  <div id="splitbar" style="-moz-user-select:none;" 
       class="ui-resizable-handle">
  </div>
</div>
<script type="text/javascript">
/* @license magnet:?xt=urn:btih:cf05388f2679ee054f2beb29a391d25f4e673ac3&amp;dn=gpl-2.0.txt GPL-v2 */
$(document).ready(function(){initNavTree('index.html','');});
/* @license-end */
</script>
<div id="doc-content">
<!-- window showing the filter options -->
<div id="MSearchSelectWindow"
     onmouseover="return searchBox.OnSearchSelectShow()"
     onmouseout="return searchBox.OnSearchSelectHide()"
     onkeydown="return searchBox.OnSearchSelectKey(event)">
</div>

<!-- iframe showing the search results (closed by default) -->
<div id="MSearchResultsWindow">
<iframe src="javascript:void(0)" frameborder="0" 
        name="MSearchResults" id="MSearchResults">
</iframe>
</div>

<div class="PageDoc"><div class="header">
  <div class="headertitle">
<div class="title">CryptoAuthLib - Microchip CryptoAuthentication Library </div>  </div>
</div><!--header-->
<div class="contents">
<div class="textblock"><h2>Introduction </h2>
<p>This code base implements an object-oriented C library which supports Microchip CryptoAuth devices. The family of devices supported currently are:</p>
<ul>
<li><a href="http://www.microchip.com/ATSHA204A">ATSHA204A</a></li>
<li><a href="http://www.microchip.com/ATECC108A">ATECC108A</a></li>
<li><a href="http://www.microchip.com/ATECC508A">ATECC508A</a></li>
<li><a href="http://www.microchip.com/ATECC608A">ATECC608A</a></li>
</ul>
<p>Online documentation is at <a href="https://microchiptech.github.io/cryptoauthlib/">https://microchiptech.github.io/cryptoauthlib/</a></p>
<p>Latest software and examples can be found at:</p><ul>
<li><a href="http://www.microchip.com/SWLibraryWeb/product.aspx?product=CryptoAuthLib">http://www.microchip.com/SWLibraryWeb/product.aspx?product=CryptoAuthLib</a></li>
<li><a href="https://github.com/MicrochipTech/cryptoauthtools">https://github.com/MicrochipTech/cryptoauthtools</a></li>
</ul>
<p>Prerequisite skills:</p><ul>
<li>strong C programming and code reading</li>
<li>Atmel Studio familiarity</li>
<li>Knowledge of flashing microcontrollers with new code</li>
<li>Familiarity with Microchip CryptoAuth device functionality</li>
</ul>
<p>Prerequisite hardware to run CryptoAuthLib examples:</p><ul>
<li><a href="http://www.microchip.com/atsamr21-xpro">ATSAMR21 Xplained Pro</a> or <a href="http://www.microchip.com/ATSAMD21-XPRO">ATSAMD21 Xplained Pro</a></li>
<li><a href="http://www.microchip.com/developmenttools/productdetails.aspx?partno=atcryptoauth-xpro-b">CryptoAuth Xplained Pro Extension</a> or <a href="http://www.microchip.com/developmenttools/productdetails.aspx?partno=at88ckscktsoic-xpro">CryptoAuthentication SOIC Socket Board</a> to accept SOIC parts</li>
</ul>
<p>For most development, using socketed top-boards is preferable until your configuration is well tested, then you can commit it to a CryptoAuth Xplained Pro Extension, for example. Keep in mind that once you lock a device, it will not be changeable.</p>
<p>There are two major compiler defines that affect the operation of the library.</p><ul>
<li>ATCA_NO_POLL can be used to revert to a non-polling mechanism for device responses. Normally responses are polled for after sending a command, giving quicker response times. However, if ATCA_NO_POLL is defined, then the library will simply delay the max execution time of a command before reading the response.</li>
<li>ATCA_NO_HEAP can be used to remove the use of malloc/free from the main library. This can be helpful for smaller MCUs that don't have a heap implemented. If just using the basic API, then there shouldn't be any code changes required. The lower-level API will no longer use the new/delete functions and the init/release functions should be used directly.</li>
</ul>
<h2>Examples </h2>
<ul>
<li>Watch <a href="http://www.microchip.com/design-centers/security-ics/cryptoauthentication/overview">CryptoAuthLib Documents</a> for new examples coming online.</li>
<li>Node Authentication Example Using Asymmetric PKI is a complete, all-in-one example demonstrating all the stages of crypto authentication starting from provisioning the Crypto Authentication device ATECC608A/ATECC508A with keys and certificates to demonstrating an authentication sequence using asymmetric techniques. <a href="http://www.microchip.com/SWLibraryWeb/product.aspx?product=CryptoAuthLib">http://www.microchip.com/SWLibraryWeb/product.aspx?product=CryptoAuthLib</a></li>
</ul>
<h2>Release notes </h2>
<p>05/17/2019</p><ul>
<li>Added support for TNG devices (cert transforms, new API)</li>
<li>atcab_write_pub_key() now works when the data zone is unlocked</li>
</ul>
<p>03/04/2019</p><ul>
<li>mbed TLS wrapper added</li>
<li>Minor bug fixes</li>
</ul>
<p>01/25/2019</p><ul>
<li>Python JWT support</li>
<li>Python configuration structures added</li>
<li>Restructure of secure boot app</li>
</ul>
<p>01/04/2019</p><ul>
<li>Added GCM functions</li>
<li>Split AES modes into separate files</li>
<li>Bug fix in SWI START driver</li>
</ul>
<p>10/25/2018</p><ul>
<li>Added basic certificate functions to the python wrapper.</li>
<li>Added Espressif ESP32 I2C driver.</li>
<li>Made generic Atmel START drivers to support most MCUs in START.</li>
<li>Added AES-CTR mode functions.</li>
<li>Python wrapper functions now return single values with AtcaReference.</li>
<li>Added mutex support to HAL and better support for freeRTOS.</li>
</ul>
<p>08/17/2018</p><ul>
<li>Better support for multiple kit protocol devices</li>
</ul>
<p>07/25/2018</p><ul>
<li>Clean up python wrapper</li>
</ul>
<p>07/18/2018</p><ul>
<li>Added ATCA_NO_HEAP define to remove use of malloc/free.</li>
<li>Moved PEM functions to their own file in atcacert.</li>
<li>Added wake retry to accomodate power on self test delay.</li>
<li>Added ca_cert_def member to <a class="el" href="a01061.html">atcacert_def_s</a> so cert chains can be traversed as a linked list.</li>
</ul>
<p>03/29/2018</p><ul>
<li>Added support for response polling by default, which will make commands return faster (define ATCA_NO_POLL to use old delay method).</li>
<li>Removed atcatls related files as they were of limited value.</li>
<li>Test framework generates a prompt before locking test configuration.</li>
<li>Test framework puts device to sleep between tests.</li>
<li>Fixed mode parameter issue in <a class="el" href="a00994.html#gabf2abd4bd62f47537756c9ab109050c0" title="Calculate the PubKey digest created by GenKey and saved to TempKey.">atcah_gen_key_msg()</a>.</li>
<li>ATECC608A health test error code added.</li>
</ul>
<p>01/15/2018</p><ul>
<li>Added AES-128 CBC implementation using AES command</li>
<li>Added AES-128 CMAC implementation using AES command</li>
</ul>
<p>11/22/2017</p><ul>
<li>Added support for FLEXCOM6 on SAMG55 driver</li>
</ul>
<p>11/17/2017</p><ul>
<li>Added library support for the ATECC608A device</li>
<li>Added support for Counter command</li>
<li>atca_basic functions and tests now split into multiple files based on command</li>
<li>Added support for multiple base64 encoding rules</li>
<li>Added support for JSON Web Tokens (jwt)</li>
<li>Fixed <a class="el" href="a00991.html#ga14cf75d1be264ac1125087d76ee6344c" title="Executes the Write command, which performs an encrypted write of a 32 byte block into given slot.">atcab_write_enc()</a> function to encrypt the data even when the device is unlocked</li>
<li>Fixed <a class="el" href="a00311.html#aeeff0177acf29e6e7b134a14d7119d69" title="Encode data as base64 string with ruleset option.">atcab_base64encode_()</a> for the extra newline</li>
<li>Updated <a class="el" href="a00991.html#gab6e0c175cbcb5f794b12a8ec22485176" title="ECDH command with a private key in a slot and the premaster secret is read from the next slot.">atcab_ecdh_enc()</a> to work more consistently</li>
</ul>
<p>07/01/2017</p><ul>
<li>Removed assumption of SN[0:1]=0123, SN[8]=EE. SN now needs to be passed in for functions in atca_host and atca_basic functions will now read the config zone for the SN if needed.</li>
<li>Renamed atcab_gendig_host() to <a class="el" href="a00991.html#ga70751ea87f2cf913986bc7bca2cc661f" title="Issues a GenDig command, which performs a SHA256 hash on the source data indicated by zone with the c...">atcab_gendig()</a> since it's not a host function. Removed original <a class="el" href="a00991.html#ga70751ea87f2cf913986bc7bca2cc661f" title="Issues a GenDig command, which performs a SHA256 hash on the source data indicated by zone with the c...">atcab_gendig()</a>, which had limited scope.</li>
<li>Fixed <a class="el" href="a00994.html#gab17435577e546d2954bd697f21e6d3cc" title="This function generates an HMAC / SHA-256 hash of a key and other information.">atcah_hmac()</a> for host side HMAC calculations. Added <a class="el" href="a00991.html#ga45f1d09a51f7a1f68916536ab5125b9d" title="Issues a HMAC command, which computes an HMAC/SHA-256 digest of a key stored in the device,...">atcab_hmac()</a>.</li>
<li>Removed unnecessary ATCADeviceType parameters from some atca_basic functions.</li>
<li>Added <a class="el" href="a00990.html#gabd66cb9a5c50c7c62e3bc0a8ff0fc4d6" title="Creates a CSR specified by the CSR definition from the ATECC508A device. This process involves readin...">atcacert_create_csr()</a> to create a signed CSR.</li>
<li>New HAL implementation for Kit protocol over HID on Linux. Please see the Incorporating CryptoAuthLib in a Linux project using USB HID devices section in this file for more information.</li>
<li>Added <a class="el" href="a00990.html#ga71ea9d7c93c2fecb87a36b1343397fad" title="Take a full certificate and write it to the ATECC508A device according to the certificate definition.">atcacert_write_cert()</a> for writing certificates to the device.</li>
<li>Added support for dynamic length certificate serial numbers in atcacert.</li>
<li>Added <a class="el" href="a00991.html#gabf2b29b4d3ae926b63c403d084380dbe" title="Executes the Write command, which writes either one four byte word or a 32-byte block to one of the E...">atcab_write()</a> for lower level write commands.</li>
<li>Fixed <a class="el" href="a00994.html#ga47853951c57803eff1432780bf360057" title="This function calculates the input MAC for the Write command.">atcah_write_auth_mac()</a>, which had wrong OpCode.</li>
<li>Added <a class="el" href="a00991.html#ga694d921c7bc17a0e158ef96e3d476700" title="Executes the Verify command, which takes an ECDSA [R,S] signature and verifies that it is correctly g...">atcab_verify()</a> command for lower level verify commands.</li>
<li>Added <a class="el" href="a00991.html#gae8cc7670847805423ad591985eecd832" title="Executes the Verify command, which verifies a signature (ECDSA verify operation) with a public key st...">atcab_verify_stored()</a> for verifying data with a stored public key.</li>
<li>Removed atcab_write_bytes_slot(). Use <a class="el" href="a00991.html#gac395a7e195aa3cf28b48de345755feb0" title="Executes the Write command, which writes data into the configuration, otp, or data zones with a given...">atcab_write_bytes_zone()</a> instead.</li>
<li>Modified <a class="el" href="a00991.html#gac395a7e195aa3cf28b48de345755feb0" title="Executes the Write command, which writes data into the configuration, otp, or data zones with a given...">atcab_write_bytes_zone()</a> and <a class="el" href="a00991.html#ga750704332198726725a327344f4f7dd5" title="Used to read an arbitrary number of bytes from any zone configured for clear reads.">atcab_read_bytes_zone()</a> to specify a slot</li>
<li>Added <a class="el" href="a00991.html#gacf9a0c7772ebb65b87c4a4788850702b" title="Executes the Verify command in Validate mode to validate a public key stored in a slot.">atcab_verify_validate()</a> and <a class="el" href="a00991.html#ga9393b545b2fa1fdd539672a0428a30ab" title="Executes the Verify command in Invalidate mode which invalidates a previously validated public key st...">atcab_verify_invalidate()</a></li>
<li>Improvements to host functions to handle more cases.</li>
<li>Added <a class="el" href="a00991.html#ga416e4aeacf3acc35b1d5b76028c6947d" title="Executes UpdateExtra command to update the values of the two extra bytes within the Configuration zon...">atcab_updateextra()</a>, atcab_derive_key()</li>
<li>Added support for more certificate formats.</li>
<li>Added general purpose hardware SHA256 functions. See <a class="el" href="a00991.html#ga4bf8b665fe1712626a480742c2daa16b" title="Use the SHA command to compute a SHA-256 digest.">atcab_hw_sha2_256()</a>.</li>
<li>Removed device specific config read/write. Generic now handles both.</li>
<li>Removed unnecessary response parameter from lock commands.</li>
<li>Enhanced and added unit tests.</li>
<li>Encrypted read and write functions now handle keys with SlotConfig.NoMac set</li>
<li><a class="el" href="a00991.html#gadb91d2c3601b95f0ad413cf84a4dfd87" title="Compares a specified configuration zone with the configuration zone currently on the device.">atcab_cmp_config_zone()</a> handles all devices now.</li>
<li>Fixed some edge cases in <a class="el" href="a00991.html#ga750704332198726725a327344f4f7dd5" title="Used to read an arbitrary number of bytes from any zone configured for clear reads.">atcab_read_bytes_zone()</a>.</li>
<li>Updated <a class="el" href="a00987.html#ga44ad135152469c980f9bf36a5f1477bb" title="ATCACommand SHA method.">atSHA()</a> to work with all devices.</li>
<li>Fixed <a class="el" href="a00990.html#ga84f1aeed7b88889d5bf01f21dbaaf398" title="Add all the device locations required to rebuild the specified certificate (cert_def) to a device loc...">atcacert_get_device_locs()</a> when using stored sn.</li>
</ul>
<p>01/08/2016</p><ul>
<li>New HAL implementations for<ul>
<li>Single Wire interface for SAMD21 / SAMR21</li>
<li>SAMV71 I2C HAL implementation</li>
<li>XMega A3Bu HAL implementation</li>
</ul>
</li>
<li>Added <a class="el" href="a00991.html#gaff701132013eaac5600dd9fd6253505d" title="basic API methods are all prefixed with atcab_ (CryptoAuthLib Basic) the fundamental premise of the b...">atcab_version()</a> method to return current version string of libary to application</li>
<li>New Bus and Discovery API<ul>
<li>returns a list of ATCA device configurations for each CryptoAuth device found</li>
<li>currently implemented on SAMD21/R21 I2C, SAMV71</li>
<li>additional discovery implementations to come</li>
</ul>
</li>
<li>TLS APIs solidified and documented</li>
<li>Added missing doxygen documentation for some CryptoAuthLib methods</li>
<li>Stubs for HAL SPI removed as they are unused for SHA204A and ECC508A support</li>
<li>bug fixes</li>
<li>updated <a class="el" href="a00991.html#ga31d269ccdafd08519a899a8aebf53df1" title="Use the SHA command to compute a SHA-256 digest.">atcab_sha()</a> to accept a variable length message that is &gt; 64 bytes and not a multiple of 64 bytes (the SHA block size).</li>
<li>refactored Cert I/O and Cert Data tests to be smaller</li>
<li>'uncrustify' source formatting</li>
<li>published on GitHub</li>
</ul>
<p>9/19/2015</p><ul>
<li>Kit protocol over HID on Windows</li>
<li>Kit protocol over CDC on Linux</li>
<li>TLS integration with ATECC508A</li>
<li>Certificate I/O and reconstruction</li>
<li>New SHA2 implementation</li>
<li>Major update to API docs, Doxygen files found in cryptoauthlib/docs</li>
<li>load cryptoauthlib/docs/index.html with your browser</li>
</ul>
<h2>Host Device Support </h2>
<p>CryptoAuthLib will run on a variety of platforms from small micro-controllers to desktop host systems. The current list of hardware abstraction layer support includes:</p>
<p>Rich OS Hosts:</p><ul>
<li>Linux Kit Protocol over CDC USB</li>
<li>Linux Kit Protocol over HID USB</li>
<li>Linux I2C protocol.</li>
<li>Windows Kit Protocol over CDC USB</li>
<li>Windows Kit Protocol over HID USB</li>
</ul>
<p>Microcontrollers:</p><ul>
<li>SAMD21 (I2C, SWI, and Bit Banging)</li>
<li>SAMR21 (I2C and SWI)</li>
<li>SAM4S (I2C)</li>
<li>SAMV71 (I2C)</li>
<li>SAMB11 (I2C)</li>
<li>SAMG55 (I2C)</li>
<li>AVR XMEGA A3BU (I2C and SWI)</li>
<li>AVR AT90USB1287 (I2C and SWI)</li>
<li>PIC32MX695F512H (I2C)</li>
</ul>
<p>If you have specific microcontrollers or Rich OS platforms you need support for, please contact us through the Microchip portal with your request.</p>
<h2>CryptoAuthLib Architecture </h2>
<p>See the 'docs' directory of CryptoAuthLib for supporting documentation including architecture diagrams and more detailed usage docs.</p>
<p>The library is structured to support portability to:</p><ul>
<li>multiple hardware/microcontroller platforms</li>
<li>multiple environments including bare-metal, Windows, and Linux OS</li>
<li>multiple chip communication protocols (I2C, SPI, UART, and SWI)</li>
</ul>
<p>All platform dependencies are contained within the HAL (hardware abstraction layer).</p>
<div class="image">
<img src="CryptoAuthLib-Architecture.png" alt="CryptoAuthLib-Architecture.png"/>
<div class="caption">
CryptoAuthLib Architecture</div></div>
<p>There are three primary object types in CryptoAuthLib:</p><ul>
<li>Device (ATCADevice)</li>
<li>Command (ATCACommand)</li>
<li>Interface (ATCAIface)</li>
</ul>
<p>ATCADevice is a composite object made up of ATCACommand ATCAIface.</p>
<div class="image">
<img src="ATCADevice.png" alt="ATCADevice.png"/>
<div class="caption">
ATCADevice</div></div>
 <div class="image">
<img src="ATCAIFace.png" alt="ATCAIFace.png"/>
<div class="caption">
ATCAIface</div></div>
 <div class="image">
<img src="ATCAHal.png" alt="ATCAHal.png"/>
<div class="caption">
Hardware abstraction layer</div></div>
<p>Currently, the vast majority of testing has been performed on:</p>
<ul>
<li>ATSAMR21 Xplained Pro</li>
<li>ATSAMD21 Xplained Pro</li>
<li>ATSAMV71 Xplained Pro</li>
<li>Windows (kit protocol HID)</li>
</ul>
<p>These host containers implement a host test environment and test console to exercise tests. They presume that a CryptoAuth Xplained Pro or other I2C socket for an ATECC608A/ATECC508A/ATECC108A/ATSHA204A are connected to the I2C pins of the host Xplained Pro development board or in the case of windows is using a HID connection to an ATCK101 or ATCK590.</p>
<p>The unit tests and basic tests exercise the core datasheet commands of the device as well as the more convenient, basic API methods.</p>
<p>If you need an example of how to use a command, these hosts and tests are a good place to reference.</p>
<h2>Object Architecture </h2>
<p>Even though this is a C library, it follows object-oriented design patterns.</p>
<p>An object is minimally defined to be data and the actions which operate on that data.</p>
<p>Each CryptoAuth device is a composite object, a structure which includes the command table (list of commands) which are valid for the device, and the data used to hold the state of that device.</p>
<p>ATCADevice is the object which represents the Microchip CryptAuth device</p>
<p>ATCACommand is the object which represents the valid methods of the Device.</p>
<p>ATCAInterface is the physical interface object (I2C or SWI instance). Currently, each Device may have a single OATCAInterface.</p>
<p>ATCADevice represents an ATSHA or ATECC family device.</p>
<p>In order to add new protocol support for a platform, you provide a HAL (hardware abstraction layer) C file for the protocol and target. In your project's IDE or Makefile, you select which HAL support you need for the hardware configuration. Generally, there are separate files for each protocol and platform combination - (ie: samd21_i2c_asf.c would target SAMD21 MCUs with I2C using the ASF low-level driver support.)</p>
<h2>Directory Structure </h2>
<div class="fragment"><div class="line">docs - AppNotes and Doxygen HTML documentation for the library API. Load &quot;docs/html/index.html&quot; in your browser</div><div class="line">lib - primary library source code</div><div class="line">lib/atcacert - certificate data and i/o methods</div><div class="line">lib/basic - the Basic API way to access the core classes</div><div class="line">lib/crypto - Software crypto implementations (primarily SHA1 and SHA256)</div><div class="line">lib/hal - hardware abstraction layer code for supporting specific platforms</div><div class="line">lib/host - support functions for common host-side calculations</div><div class="line">lib/jwt - json web token functions</div><div class="line">test - unit tests. See test/cmd-processor.c for main() implementation.</div><div class="line"></div><div class="line">For production code, test directories should be excluded by not compiling it</div><div class="line">into a project, so it is up to the developer to include or not as needed.  Test</div><div class="line">code adds significant bulk to an application - it&#39;s not intended to be included</div><div class="line">in production code.</div></div><!-- fragment --><h2>Tests </h2>
<p>There is a set of unit tests found in the test directory which will at least partially demonstrate the use of the objects. Some tests may depend upon a certain device being configured in a certain way and may not work for all devices or specific configurations of the device.</p>
<p>The test/cmd-processor.c file contains a main() function for running the tests. It implements a command-line interface. Typing help will bring up the list of commands available.</p>
<p>One first selects a device type, with one of the following commands:</p><ul>
<li>204 (ATSHA204A)</li>
<li>108 (ATECC108A)</li>
<li>508 (ATECC508A)</li>
<li>608 (ATECC608A)</li>
</ul>
<p>From there the following unit test sweets are available:</p><ul>
<li>unit (test command builder functions)</li>
<li>basic (test basic API functions)</li>
<li>cio (test certification i/o functions)</li>
<li>cd (test certificate data functions)</li>
<li>util (test utility functions)</li>
<li>crypto (test software crypto functions)</li>
</ul>
<p>Unit tests available depend on the lock level of the device. The unit tests won't lock the config or data zones automatically to allow retesting at desired lock levels. Therefore, some commands will need to be repeated after locking to exercise all available tests.</p>
<p>Starting from a blank device, the sequence of commands to exercise all unit tests is: </p><div class="fragment"><div class="line">unit</div><div class="line">basic</div><div class="line">lockcfg</div><div class="line">unit</div><div class="line">basic</div><div class="line">lockdata</div><div class="line">unit</div><div class="line">basic</div><div class="line">cio</div><div class="line">cd</div><div class="line">util</div><div class="line">crypto</div></div><!-- fragment --><h1>Using CryptoAuthLib (Microchip CryptoAuth Library) </h1>
<p>Using a new library is often easier when you can load an example and see how it works. We've provided examples in the form of "host containers" which are host projects that incorporate CryptoAuthLib and target various processors or communication APIs.</p>
<p>We maintain host test containers for each of the HAL layers we support. We've published the host container for SAMD21 which demonstrates a simple console interface to invoke test runners.</p>
<p>Look for SAMD21 Unit Tests CryptoAuthLib at <a href="http://www.microchip.com/SWLibraryWeb/product.aspx?product=CryptoAuthLib">http://www.microchip.com/SWLibraryWeb/product.aspx?product=CryptoAuthLib</a></p>
<p>The best way to learn how to use CryptoAuthLib is to study the host test projects that exercise the library and ATECC and ATSHA devices.</p>
<p>New examples will be forthcoming as the software matures. Continue checking the <a href="http://www.microchip.com/design-centers/security-ics/cryptoauthentication/overview">CryptoAuthentication</a> web page for new updates.</p>
<h2>Using Git to Incorporate CryptoAuthLib as a Submodule </h2>
<p>You can include this project in your own project under git.</p>
<p>Using CryptoAuthLib as a git submodule, you can maintain your application separately from CryptoAuthLib.</p>
<p>If your project is already in git but you haven't yet intergrated CryptoAuthLib, change to the directory where you want to put CryptoAuthLib</p>
<div class="fragment"><div class="line">git submodule add -b master &lt;giturl to CryptoAuthLib&gt;</div></div><!-- fragment --><p>This adds CryptoAuthLib as a subdirectory and separate git repo within your own project. Changes and commits to your project vs CryptoAuthLib will remain separated into each respective repository.</p>
<p>If there is a project you want to checkout that already incorporates CryptoAuthLib as a submodule if you clone the repo that incorporates CryptoAuthLib, after cloning, you'll still need to fill out the CryptoAuthLib submodule after cloning: </p><div class="fragment"><div class="line">git submodule init</div><div class="line">git submodule update --remote</div><div class="line">cd cryptoauthlib</div><div class="line">git checkout master</div></div><!-- fragment --><p>Now that CryptoAuthLib is a full-fledged submodule in your git project, in order to easily add it to your project within Atmel Studio, please see this <a href="http://avrstudio5.wordpress.com/2011/07/12/tip-add-existing-multiple-files-and-folders-to-an-avr-studio-project-quickly/">tip</a></p>
<h2>Incorporating CryptoAuthLib in a project </h2>
<p>1) In your Makefile or IDE, choose the HAL support you need from the HAL directory and exclude other HAL files from your project.</p>
<p>2) For I2C interfaces, define the symbol ATCA_HAL_I2C in your compiler's symbol definitions. This will hook up the CryptoAuthLib interface class with your HAL implementation of I2C methods.</p>
<p>3) HAL implementations for CDC and HID interfaces to the ATCK101 are also included for use with Windows or Linux versions of the test host.</p>
<h2>Incorporating CryptoAuthLib in a Linux project using USB HID devices </h2>
<p>The Linux HID HAL files use the Linux udev development software package.</p>
<p>To install the udev development package under Ubuntu Linux, please type the following command at the terminal window:</p>
<div class="fragment"><div class="line">sudo apt-get install libudev-dev</div></div><!-- fragment --><p>This adds the udev development development software package to the Ubuntu Linux installation.</p>
<p>The Linux HID HAL files also require a udev rule to be added to change the permissions of the USB HID Devices. Please add a new udev rule for the Microchip CryptoAuth USB devices.</p>
<div class="fragment"><div class="line">cd /etc/udev/rules.d</div><div class="line">sudo touch mchp-cryptoauth.rules</div></div><!-- fragment --><p>Edit the mchp-cryptoauth.rules file and add the following line to the file: </p><div class="fragment"><div class="line">SUBSYSTEM==&quot;hidraw&quot;, ATTRS{idVendor}==&quot;03eb&quot;, ATTRS{idProduct}==&quot;2312&quot;, MODE=&quot;0666&quot;</div></div><!-- fragment --> </div></div><!-- PageDoc -->
</div><!-- contents -->
</div><!-- doc-content -->
<!-- start footer part -->
<div id="nav-path" class="navpath"><!-- id is needed for treeview function! -->
  <ul>
    <li class="footer">Generated by
    <a href="http://www.doxygen.org/index.html">
    <img class="footer" src="doxygen.png" alt="doxygen"/></a> 1.8.15 </li>
  </ul>
</div>
</body>
</html>
